The mata magic

The mata magic is used to execute Mata code. Mata is a matrix programming language that can be used by those who want to do matrix computations interactively and by those who want to add new features to Stata. You can read about all of Mata’s features here.

The mata magic can be used as both a line magic and a cell magic command. When used as a line magic, it allows you to either execute a single-line Mata statement or enter Mata’s interactive environment. You can type %%mata? to view its documentation.

[23]:
%%mata?

Docstring:

Execute one line or a block of Mata code.

When the %mata line magic command is used, one line of Mata code can be specified and executed. This is similar to specifying mata: istmt within Stata. When the %%mata cell magic command is used, a block of Mata code can be specified. The code is executed just as it would be in a do-file.

Cell magic syntax:

%%mata [-m ARRAYLIST] [-outm MATLIST] [-qui] [-c]

  Execute a block of Mata code. This is equivalent to running a
  block of Mata code within a do-file. You do not need to
  explicitly place the code within the mata[:] and end block.

  Optional arguments:

    -m ARRAYLIST      Load multiple NumPy arrays into Mata's
                      interactive environment. The array names
                      should be separated by commas. Each array is
                      stored in Mata as a matrix with the same name.

    -outm MATLIST     Save Mata matrices as NumPy arrays when the
                      cell completes. The matrix names should be
                      separated by commas. Each matrix is stored
                      in Python as a NumPy array.

    -qui              Run Mata code but suppress output.

    -c                This argument specifies that Mata code be
                      executed in mata: mode. This means that
                      if Mata encounters an error, it will stop
                      execution and return control to Python. The
                      error will then be thrown as a Python SystemError
                      exception.

Line magic syntax:

%mata [-c]

  Enter Mata's interactive environment. This is equivalent to
  typing mata or mata: in the Stata Command window.

  Optional argument:

    -c                Enter interactive Mata environment in mata:
                      mode. The default is to enter in mata mode.

%mata istmt

  Run a single-line Mata statement. This is equivalent to executing
  mata: istmt within Stata.

%%mata cell magic

The %%mata magic is used to execute multiple lines of Mata code at once. This is similar to executing Mata code within a mata[:] and end block in a do-file. See [M-3] mata for more information about how to invoke Mata.

[24]:
%%mata
a = 3

/* create an NxN identity matrix */
real matrix id(real scalar n)
{
    real scalar i
    real matrix res

    res = J(n, n, 0)
    for (i=1; i<=n; i++) {
        res[i,i] = 1
    }
    return(res)
}

B = id(a)
B

. mata
------------------------------------------------- mata (type end to exit) -----
: a = 3

:
: /* create an NxN identity matrix */
: real matrix id(real scalar n)
> {
>     real scalar i
>     real matrix res
>
>     res = J(n, n, 0)
>     for (i=1; i<=n; i++) {
>         res[i,i] = 1
>     }
>     return(res)
> }

:
: B = id(a)

: B
[symmetric]
       1   2   3
    +-------------+
  1 |  1          |
  2 |  0   1      |
  3 |  0   0   1  |
    +-------------+

: end
-------------------------------------------------------------------------------

.

Arguments

By default, code is executed in mata mode. This means that even if an error occurs, Mata will continue execution until the last Mata statement in the block has run to completion.

In the following cell, we specify an undefined number, unknown, as the dimension of the identity matrix; although this causes Mata to return an error, the following statement is still executed.

[25]:
%%mata
C = id(unknown)
display("This line will still be printed.")

. mata
------------------------------------------------- mata (type end to exit) -----
: C = id(unknown)
                 <istmt>:  3499  unknown not found
r(3499);

: display("This line will still be printed.")
This line will still be printed.

: end
-------------------------------------------------------------------------------

.

-c

This argument specifies that Mata code be executed in mata: mode. This means that if Mata encounters an error, it will stop execution and return control to Python. The error will then be thrown as a Python SystemError exception.

For example, when we add the -c argument to the code above, we see that Python raises an exception and the error code is returned after having exited the Mata environment.

[26]:
%%mata -c
C = id(unknown)
display("This line will not be printed.")
Exception in thread Stata:
Traceback (most recent call last):
  File "c:\users\zxx\appdata\local\programs\python\python37\lib\threading.py", line 926, in _bootstrap_inner
    self.run()
  File "C:/Program Files/Stata17/utilities\pystata\core\stout.py", line 176, in run
    raise SystemError(output)
SystemError:
. mata:
------------------------------------------------- mata (type end to exit) -----
: C = id(unknown)
                 <istmt>:  3499  unknown not found
(1 line skipped)
-------------------------------------------------------------------------------
r(3499);
r(3499);


-qui

The -qui argument specifies to execute the block of Mata code but suppress the output.

[27]:
%%mata -qui
/*no output*/
C = id(5)
C

-m ARRAYLIST

This argument loads one or multiple NumPy arrays into Mata’s interactive environment, storing each array into a matrix with the same name. To load multiple arrays, specify a list with array names separated by commas. There should be no whitespace between the names unless you enclose the list within single quotes () or double quotes ().

-outm MATLIST

This argument saves one or multiple Mata matrices as NumPy arrays when the cell completes execution; each matrix is stored as a separate NumPy array in Python. To export multiple matrices, specify a list with matrix names separated by commas. There should be no whitespace between the names unless you enclose the list within single quotes () or double quotes ().

In the following, we create a 5x5 NumPy array with random values and a 4x4 identity NumPy array, and we load the two arrays into Mata.

[28]:
import numpy as np

np.random.seed(17)
npa = np.random.random((5,5))
npb = np.identity(4)
[29]:
%%mata -m npa,npb
npa
npb

. mata
------------------------------------------------- mata (type end to exit) -----
: npa
                 1             2             3             4             5
    +-----------------------------------------------------------------------+
  1 |  .2946650027   .5305867556   .1915207869   .0679003582     .78698546  |
  2 |  .6563335218    .637520896   .5756028938   .0390629162   .3578136045  |
  3 |  .9456831868   .0600446803   .8640421035   .8772905261   .0511936656  |
  4 |  .6524186155   .5517513686   .5975132532   .4835286243   .2829881609  |
  5 |  .2977257183   .5615089053    .396047436   .7887007097   .4184843853  |
    +-----------------------------------------------------------------------+

: npb
[symmetric]
       1   2   3   4
    +-----------------+
  1 |  1              |
  2 |  0   1          |
  3 |  0   0   1      |
  4 |  0   0   0   1  |
    +-----------------+

: end
-------------------------------------------------------------------------------

.

Within Mata, we calculate the singular value decomposition of npa and return the result in U, s, and Vt. Then we push those Mata matrices to Python as NumPy arrays.

[30]:
%%mata -outm U,s,Vt
U = s = Vt = .
svd(npa, U, s, Vt)

. mata
------------------------------------------------- mata (type end to exit) -----
: U = s = Vt = .

: svd(npa, U, s, Vt)

: end
-------------------------------------------------------------------------------

.
[31]:
U, s, Vt
[31]:
(array([[-0.29776638,  0.66038134, -0.08825852,  0.67569317, -0.10431127],
        [-0.41723241,  0.31691857,  0.61847411, -0.3391098 ,  0.47746629],
        [-0.56518202, -0.6740881 ,  0.10325862,  0.44410707,  0.13520756],
        [-0.47965858,  0.02588292,  0.08960879, -0.348452  , -0.79988073],
        [-0.43330038,  0.09162108, -0.76877053, -0.33135087,  0.32102154]]),
 array([[2.45473309],
        [1.01798709],
        [0.59358903],
        [0.29611096],
        [0.02692625]]),
 array([[-0.5450739 , -0.39347486, -0.50666998, -0.45056571, -0.297234  ],
        [-0.187344  ,  0.56747614, -0.2178739 , -0.44143434,  0.63288209],
        [ 0.51744255, -0.04812796,  0.29883434, -0.76525509, -0.23456257],
        [ 0.23818892, -0.70691335, -0.07257898, -0.02559534,  0.66152606],
        [-0.58593166, -0.14527762,  0.77540108, -0.12591977,  0.13592601]]))

%mata line magic

The %mata line magic can be run in two modes. The first mode is used for evaluating Mata code in an interactive environment. This is the same as typing mata or mata: in Stata’s Command window to enter Mata’s interactive environment. Within this environment, you can type Mata statements one by one and exit the environment with end.

%mata [-c]

If no Mata statement is specified and the -c argument is not specified, %mata will enter the interactive environment in mata mode. This means that even if an error occurs, you will stay in the environment until end is typed.

When -c is specified, %mata will enter the interactive environment in mata: mode. This means that if an error occurs, a Python SystemError exception is thrown and this interactive environment is ended automatically.

[32]:
%mata
. mata
------------------------------------------------- mata (type end to exit) ---
: B = Hilbert(5)

: B
[symmetric]
                 1             2             3             4             5
    +-----------------------------------------------------------------------+
  1 |            1                                                          |
  2 |           .5   .3333333333                                            |
  3 |  .3333333333           .25            .2                              |
  4 |          .25            .2   .1666666667   .1428571429                |
  5 |           .2   .1666666667   .1428571429          .125   .1111111111  |
    +-----------------------------------------------------------------------+

: end
-----------------------------------------------------------------------------

The second mode of the %mata line magic is to evaluate a single-line Mata statement in Stata.

%mata istmt

This is equivalent to executing mata: istmt in Stata.

[33]:
%mata invsym(B)
[symmetric]
             1         2         3         4         5
    +---------------------------------------------------+
  1 |       25                                          |
  2 |     -300      4800                                |
  3 |     1050    -18900     79380                      |
  4 |    -1400     26880   -117600    179200            |
  5 |      630    -12600     56700    -88200     44100  |
    +---------------------------------------------------+